/**
 * Software License, Version 1.0
 * 
 * Copyright 2008 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgment:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgment may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or Granules, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called Granules, 
 * nor may Indiana University or Community Grids Lab or Granules appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 * LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 * WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 * NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 * INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 * INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 * "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 * LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 * ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 * GENERATED USING SOFTWARE.
 */

package cgl.granules.dataset;

import java.io.IOException;

/**
 * The interface outlines the core functionalities that need to be supported
 * within datasets. There can be different kinds of datasets: streams, files
 * (pointers thereto), URIs, databases and objects.
 * 
 * @author Shrideep Pallickara
 * 
 */

public interface Dataset {
	public static final int STREAMS = 1;
	public static final int FILES = 2;
	public static final int DATABASE = 3;

	/**
	 * Indicates whether the dataset needs to be initialized prior to being
	 * used.
	 * 
	 * @return <code>true</code> if the dataset need initialization;
	 *         <code>false</code> otherwise.
	 */
	public boolean needsInitialization();

	/**
	 * Check to see if the dataset has been initialized
	 * 
	 * @return <code>true</code> if the dataset is initialized;
	 *         <code>false</code> otherwise.
	 */
	public boolean isInitialized();

	/**
	 * Invokes the initialization of the dataset. This is invoked only when the
	 * node is ready to execute the operation that will operate on this dataset.
	 * 
	 * @return <code>true</code> if the dataset has been initialized;
	 *         <code>false</code> otherwise.
	 * @throws DatasetException
	 */
	public boolean initializeDataset() throws DatasetException;

	/**
	 * Retrieve the type of the data set
	 * 
	 * @return type of the dataset
	 */
	public int getDatasetType();

	/**
	 * Retrieve a description of the dataset
	 * 
	 * @return A description of the dataset.
	 */
	public String getDescription();

	/**
	 * A check to see if the dataset is available
	 * 
	 * @return <code>true</code> if the dataset is available;<code>false</code>
	 *         otherwise.
	 */
	public boolean isAvailable();

	/**
	 * This polls the dataset to see if data is available for consumption.
	 * 
	 * @return <code>true</code> if data is available on this dataset;
	 *         <code>false</code> otherwise.
	 * @throws DatasetException
	 */
	public boolean isDataAvailable();

	/**
	 * Retrieve the last update to this dataset
	 * 
	 * @return The time at which this dataset was last updated. The time is
	 *         returned in milliseconds.
	 * */
	public long getLastModificationTime();

	/**
	 * Retrieve the identifier for this dataset. This would typically be a UUID
	 * which uniquely identifies the dataset in question.
	 * 
	 * @return The unique identifier for this dataset.
	 */
	public String getIdentifier();

	/**
	 * Close access to this dataset. This method returns true if a graceful
	 * closure of the dataset was possible. This method will try its best to
	 * close the dataset. If it fails to close the dataset an exception,
	 * outlining the problems that were encountered will, be thrown.
	 * 
	 * @return <code>true</code> if a graceful closure of this dataset was
	 *         performed;<code>false</code> otherwise.
	 * @throws DatasetException
	 */
	public boolean close() throws DatasetException;

	/**
	 * Indicates whether this dataset supports dynamic data availability
	 * notifications
	 * 
	 * @return <code>true</code> if this dataset supports data availability
	 *         notifications;<code>false</code> otherwise.
	 */
	public boolean supportsDataAvailabilityNotifications();

	/**
	 * Retrieve the data availability notifier for this dataset. This method
	 * will return a NULL if the underlying dataset does not support
	 * availability notifications.
	 * 
	 * @return The data availability notifier for this dataset.
	 */
	public DataAvailabilityNotifier getDataAvailabilityNotifier();

	/**
	 * A serialized representation of this dataset, which would allow one to
	 * reconstruct and initialize it from this marshalled representation.
	 * 
	 * @return The byte[] representation of this dataset.
	 */
	public byte[] getBytes() throws IOException;
}
